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Introduction Read Me First! 



This manual is included as a supplement to the Applied Engineering TimeMaster II 
HO. User's Manual and is intended for use by Applesoft BASIC and assembly 
language programmers It explains how to install and use the TimeMaster ProDOS 
Command Extensions. You will have no need for this information unless you are 
writing your own programs. 



About TPCE (TimeMaster ProDOS Command Extensions) 

The program file, TPCE, on the TimeMaster II H.O. ProDOS Time Utilities disk, 
when executed, will add 15 new BASIC commands. These commands provide a kit 
of convenient and powerful tools for using the many features of the TimeMaster II 
HO. clock card from within your ProDOS programs. You will be able to use these 
commands to set and display the TimeMaster II HO. time; use a Stopwatch timer 
which runs concurrently with your program; use your TimeMaster II H.O. , card as 
an alarm clock; set the desired interrupt rate; schedule a call to an assembly 
language subroutine at specific intervals; send command strings to a BSRX-10 
device; and more. The uses are limited only by your imagination! 

TPCE was designed to work with ProDOS version 1.1.1 and BASIC.SYSTEM 
version 1.1, both of which are included on the TimeMaster II H.O. ProDOS Time 
Utilities disk. TPCE will not operate with other command interpreters; only 
BASIC.SYSTEM TPCE was also designed to utilize the many features available 
ONLY on the TimeMaster II H.O. clock card. 

TPCE uses 4096 bytes of memory and installs between the ProDOS file buffers 
and BASIC.SYSTEM HIMEM is automatically lowered to $8600. The actual 
location of TPCE is from $8A00 to $99FF. 



For More Information 

This supplement assumes the reader is somewhat familiar with Apple's 
Professional Disk Operating System (ProDOS), the Applesoft BASIC programming 
language, and the internal operation of the He computer. Additional information 
can be found in the following manuals: 

Applesoft BASIC Reference Manual 
(Addison-Wesley Publishing 1-800-238-3801) 

Apple lie Reference Manual (Apple Computer, Inc.) 

ProDOS User's Manual (Apple Computer, Inc.) 

Beneath Apple ProDOS (Ouality Software) by Don Worth and Pieter 
Lechner 

BASIC Programming with ProDOS 
(Addison-Wesley Publishing 1-800-238-3801) 

TimeMaster II HO. User's Manual (Applied Engineering) 
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Getting Started what is Required 

This is all you need to use the TimeMaster ProDOS Command Extensions: 

An Apple 11+ or He (standard or enhanced) with at least 64K of memory. 
A TimeMaster II HO. card installed in the proper expansion slot, 
(see the TimeMaster II HO. User's Manual) 
One disk drive 

A monitor capable of displaying a 40 column screen 
• ProDOS 1.1.1, BASIC. SYSTEM 1 .1 and TPCE. 

The switches on the TimeMaster II HO. should be in the following configuration. 

Set-protect disabled 
TimeMaster Mode enabled 
Non-Maskable Interrupts disabled 
Interrupt Request enabled 

The revision of the TimeMaster II H.O. ROM should be .5 or greater. (The revision 
number label is on the 24 pin ROM chip on the TimeMaster II HO. card.) Earlier 
ROM will work.but make sure to use the TPCE commands to read the clock, NOT 

Applesoft BASIC IN# and PR# commands. 

Note: Apple Computer's FILER program (version 1 .1) has been included on the 
TimeMaster II HO. Time Utility disk. Please use it to make a backup copies of the 
TimeMaster II H.O. utility disks. Then store your originals in a safe place! 
CON VERT (version 1 .2) is also included to allow conversion of DOS 3.3 files to 
ProDOS format. See the TimeMaster II H.O. User's Manual for details on which 
files are convertible. 

Installing TPCE 

The installation of the TimeMaster ProDOS Command Extensions is accomplished 
by loading PRODOS, BASIC.SYSTEM, then executing the binary file named 
TPCE. TPCE can be executed from either the immediate (keyboard) or deferred 
(program) mode. TPCE can also be installed by booting the TimeMaster II HO. 
ProDOS Time Utility disk and selecting the option "Install TPCE and exit to BASIC" 
from the main menu. 

The TimeMaster II H.O. slot is automatically determined during execution of TPCE, 
which takes about two to three seconds. Successful installation from the 
immediate models indicated by an on-screen message. No message is presented 
upon successful installation from the deferred mode. 



TPCE remains active until one of the following conditions is encountered: 

•TPCE 'QUIT command 

• System power-down or re-boot 

• Execution of another ProDOS SYSTEM file. 

• Execution of another BASIC enhancement program 

(Double-Take, GPLE, APA) 



Command Syntax 

In the descriptions and examples which follow, the commands are all shown in 
upper case, with spaces inserted merely for clarity. TPCE will, however, accept 
both upper and lower case characters and ignore all spaces between commands 
and arguments. 



TimeMaster II H.O. 

ProDOS Command The New Commands 

Extensions 



This section contains descriptions of each of the 15 new BASIC TPCE commands. 
The command are grouped into four categories; time and date commands, 
stopwatch commands, interrupt commands, and miscellaneous commands. 

For your convenience, one of the new commands is HELP. The HELP command 
displays a screen full of information, listing and describing the other 14 TPCE 
commands. Figure 1 is an illustration of the HELP screen. 



Figure 1 TPCE "HELP" Screen 



TIMEMASTER PRODOS COMMAND EXTENSIONS 

TIME RETURN CURRENT DATE AND TIME 

CLOCK.. SHOW DATE AND TIME CONTINUOUSLY 
ALARM.. SETALARMATSPECIFIED TIME 
SET SETORADJUSTDATE OR TIME 

RESET.. ..STOP AND CLEAR ELAPSED TIMER 
START.... START ELAPSED TIMER 

STOP STOP ELAPSED TIMER 

TIMER.... RETURN ELAPSED TIMER VALUE 
WATCH.. SHOW ELAPSED TIMER CONTINUOUSLY 

RATE SET OR RETURN INTERRUPT RATE 

LINK LINK USER PROGRAM TO INTERRUPT 

SLOT RETURN SLOT NO. OF TIMEMASTER 

BSR SEND BSR COMMANDS (*,A~V) 

OUIT DEACTIVATE TPCE 



Time and Date Commands 

TPCE allows you to read the current time and date in any of six formats, provides 
an option to display the time and date continuously on the screen, set the 
TimeMaster II H.O. to a new time and date, and set an alarm to go off at a specified 
time. 

TIME The TIME command displays the current date and time. If no format is specified 

the default format will be used. When you specify a particular format, that format 
becomes the new default. 

TIME display date and time in the default format 

TIME: displayas: FRI 11/15/85 15:45:25 (initial default) 



TIMES 


display as: 


15-NOV-85 15:45 


TIMEM 


display as: 


11/15 15:45:25.234 


TIME& 


display as: 


FRI NOV 15 15:45:25 


TIME% 


display as: 


FRI NOV 1503:45:25 PM 


TIME# 


display as: 


85,11,05,15,15,45,25.234 



This also allows you to read the time from an Applesoft program, in whatever 
format you choose. The sample routine, below, will read the date and time in the 
":" format into the string variable TM$. 

1200 PRINT CHR$(4); "TIME:" 
1210INPUTTM$ 

The first six TIME formats above will return strings. The -#■ format returns seven 
numeric values, the sequence of which is detailed in the SET command 
description. This format would be read in the following manner: 

1200 PRINT CHR$(4) ;liME#" 
1210 INPUTY, MO, W, D, H, Ml, S 

CLOCK This displays the time and date in the MO/DD HH:MM:SS format on the screen at a 
specified position. If you do not specify a position, the display will appear on the 
top line, starting at column 26 on a 40-column screen or column 51 on an 
80-column screen. (Only standard Apple //e80-column display is supported.) 

CLOCK display at line 1 , column 26 (initial default) 

CLOCK 24,1 display at line 24, column 1 
CLOCK OFF turn off the date/time display. 

If you are using a standard Apple He 80-column display, the column number will be 
doubled and decremented by one. Therefore, CLOCK 1,26 will display the date 
and time starting at column 51 . 

You may specify any line or column number you wish, between and 99. If you 
specify a line number greater than 24, TPCE will assume you really meant 24 (the 
bottom line). If the column argument specified is larger than 26 while in the 40 
column mode, the CLOCK display will default to column 26. The display will be 
justified against the right side of the screen. The same is true for the 80 column 
display except that the default column will be 51 . 



TheCLOCKdisplay is written directly to the screen, so it will not appear on any 
other output device. If you select any line below the top line, copies of old times 
will be scrolled up the screen whenever the screen scrolls. 

ALARM This command allows you to use your l/e and TimeMaster II H.O. as an alarm 
clock. The alarm can be set to "go off" at a specific time or at an interval measured 
from the present time. The examples, below, illustrate the various arguments used 
to set the ALARM. 

ALARM +1 Set alarm to go off in ten minutes (interval) 

ALARM +3:1 5 Set alarm to go off in 3 hours and 15 minutes (interval) 

ALARM 5:30 PM Set alarm to go off at 5:30 PM 

ALARM 5:30 AM Set alarm to go off at 5:30 AM 

ALARM 1 7:30 24 hour clock notation; same as 5:30 PM 

ALARM 5:30 24 hour clock notation; same as 5:30 AM 

ALARM Silence alarm or cancel a previously set alarm. 

The alarm sounds for one minute, beeping the lie speaker at two-second intervals. 
You can silence the alarm by typing "ALARM". The beep is a lower pitch than the 
standard Apple "bell". Depending on the interrupt RATE, there are two possible 
ALARM tones. 

You can only have one alarm setting active at a time. The interval ALARM is 
accurate to the nearest TimeMaster II HO. minute cycle. 

SET This command allows you to reset the date or time on the TimeMaster II HO. card. 

There are actually six commands in one, allowing many different ways of changing 
the date and time. One of them is very useful for changing back and forth between 
Standard and Daylight Savings Time. Another makes it easy to synchronize, down 
to the second, with another clock. 

SETH Allows you to increment, decrement, or set the hour. 

SETH +x Add x to the current hour (modulo 24) 
SETH -X Subtract x from the current hour 
SETHx Set the hour to X 

The parameter "x" may be any value from to 99. The arithmetic is done modulo 
24. For example, if you type "SETH+20" when the hour is 1 1 , the result will be 7. 
(11+20 .31 .7mod24). 

In the Fall if you switch to Standard time, type SETH-1 to adjust your TimeMaster II 
H.O. When Daylight Savings Time starts, type SETH+1 . 

SETM Allows you to increment, decrement, or set the minute. 

SETM +x Add x to the current minute (modulo 60) 
SETM -X Subtract x from the current minute 
SETM X Set the minute to x 

The parameter "x" may be any value from to 99. The arithmetic is done modulo 
60. For example, if you type "SETM+20" when the minute is 51, the result will be 
11. (51 +20=71 =11mod60) 



SETW Allows you to increment, decrement, or set the day of week. 

SETW +x Add x to the current day of week (modulo 7) 
SETW -X Subtract x from the current day of week 
SETWx Set the day of week to x 

The parameter "x" may be any value from to 99. The arithmetic is done modulo 7. 
For example, if you type "SETW+5" when the day of week is 4, the result will be 2. 
(4+5= 9=2mod7) 

The days of the week are represented by the integers through 6, where 
0=Sunday, 1=Monday, 6=Saturday. 

SETT Command: lets you directly specify the time of day. 

SETT 5:30 Sets time to 5:30 AM 

SETT 5:30 PM Sets time to 5:30 PM 

SETT 17:30 24 hour clock notation; sets time to 5:30 PM 

Note that the TimeMaster II H.O. is always in 24-hour mode internally, but will 
format the time any way you wish. Remember that the hour starting at midnight is 
called either 00:xx or 12:xx AM; the hour starting at noon is called either 12:xx or 
12:xx PM. 

SETD Command: permits you to set a new date into the TimeMaster II HO, card. 
You can specify the date in either of two formats: 

SETD mm/dd/yy 
SETD yylmm/dd 

Also, you may separate the fields with any non-numeric character, including ""-"" or 
comma. TPCE distinguishes which of the two formats you have used by the fact 
the the year must be at least 85. After 1999) this feature will stop working until 
2085. If you are still using TPCE after 1 999 A.D., congratulations! 

SETS Command: stores 00 into the seconds register on the TimeMaster II HO. 
card. 

There are no parameters, you merely type "SETS" and press the RETURN key. 
This allows you to easily synchronize to the seconds display with another time 
source. Simply use the "CLOCK" command so that the time with seconds is 
continuously displayed on the screen. Then type "SETS" (don't hit RETURN yet) 
and start watching your other time source. At the instant you see 59 seconds on 
the external time source, hit the RETURN key. Then you can use SETM, SETH, or 
SETT to adjust the hours and minutes if necessary. 



Stopwatch Timer Commands 

A stopwatch-like timer is included in TPCE. It can measure time intervals with 
either second or millisecond precision, according to the interrupt RATE you select. 
The total value of the accumulated time can go to 6 days, 23 hours, 59 minutes, 
and 59.999 seconds. (After that it starts over.) 



If you have the interrupt rate set at one-per-second, the times are also useful for 
timing programs. If the interrupt rate is set at 1024-per-second, the interrupt 
overhead slows the Apple down significantly; in this case, timing of program 
execution is meaningless. The faster interrupt rate is quite handy for timing 
external events, though. 

At the 1024-per-second interrupt rate, a six-digit counter is incremented by 

.000977 on every interrupt. The counter is initialized to .000528 when the second 

ticks. If you do disk I/O or other operations which disable the interrupts, some 

millisecond ticks may be missed. On the next second tick, the milliseconds will be 

re-synchronized. 



RESET This command stops the stopwatch if it is running, and clears the accumulated 

time to 0. 



START This command starts the stopwatch from where it last stopped. (If the stopwatch 

is already running, this does nothing.) 

STOP This stops the stopwatch timer, unless it is already stopped. 



WATCH This command is similar to the CLOCK command, except that the stopwatch time 

is displayed continuously rather than the date/time. The default position is line 1, 
column 1. You may place it anywhere on the screen, just like the CLOCK 
command. Both CLOCK and WATCH can be active at the same time. 

WATCH Display stopwatch value at line 1 , column 1 

WATCH 13,5 Display stopwatch value at line 13, column 5 

WATCH OFF Turn off stopwatch display 

The display will show millisecond values if the interrupt rate is set to 
1024-per-second. At a one-per-second rate, the millisecond display will always 
show". 000". 
TIMER The stopwatch value at the instant this command is entered is displayed. If you 

issue this command from an Applesoft program, a following INPUT statement will 
read the stopwatch time into a string variable: 

1200 PRINT CHR$(4);"TIMER" 
1210 INPUT SW$ 



Interrupt Commands 



RATE This command sets the interrupt rate, and displays the setting. You may select 
one of three interrupt rates: never, slow, and fast. When you first install TPCE, 
the interrupt rate is set at 1 Hz (once per second). Consequently, all times will be 
shown in exact seconds, with .000" for the millisecond portion. If you use the 
RATE command to change this rate to 1024-per-second, milliseconds will be 
counted and displayed. 

RATE display the current RATE selection 

RATE stop the interrupts (until a new RATE) 

RATE 1 interrupt at 1 024-per-second rate 

RATE 2 interrupt at one-per-second rate (initial default) 

In all four cases, TPCE responds by printing the selected rate. If you issue the 
RATE command from an Applesoft program, follow it with an INPUT command to 
read the rate into a string variable. 

The overhead at the 1024-per-second rate is extremely high, slowing execution of 
programs down to a snails pace (still faster than some other personal computers, 
though). This overhead is mostly inside the Apple monitor ROM and the ProDOS 
interrupt handler. 

LINK This allows you to schedule your assembly language subroutine to be called (with 

a JSR command) at a specific interval. The examples, below illustrate this. 

LINK $300 JSR $300 at every TimeMaster II HO. interrupt 

LINK 0:0:1 0,$300 JSR $300 every 1 seconds 

LINK 5:20,$300 JSR $300 every 5 hours, 20 minutes 

LINK stop calling your interrupt subroutine 

When your interrupt subroutine is called, the registers have already been saved. 
You can do whatever you wish, then return with an RTS instruction. You cannot 
depend on the monitor ROM being switched on; in fact, it probably will not be. If 
you change any soft-switches, be sure to put them back like they were before you 
return. 

If the carry flag is set when you return from your interrupt subroutine, the LINK will 
stay engaged. If carry is clear, the LINK will be disabled. 

Miscellaneous Commands 

BSR This command allows you to send command strings to your BSR X-1 device, 

assuming you have one connected to your TimeMaster II HO. The format is 
straightforward: 

BSR xxxx where "xxxx" indicates any string of BSR codes. 

The valid BSR codes are the letters A through V, and (See pages 11-14 of the 
TimeMaster II HO. User's Manual.) 



SLOT This command returns the slot number of the TimeMaster II HO. card. If you issue 
this command from an Applesoft program, follow it with an INPUT command to 
read the slot number: 

1200 PRINT CHR$(4);"SL0T 
1210 INPUTS 



QUIT This command removes all trace of TPCE from memory. (Don't worry, it is still on 

the disk.) The installation process is reversed, returning BASIC. SYSTEM to its 
original state. 



HELP This command displays the HELP screen, providing an on-screen summary of 

WOE commands. 

Calling TPCE from You can use TPCE from assembly language programs, as long as you are 

Assembly Language operating under BASIC. SYSTEM. There are two pre-defined entry points. 
Programs 

JSR $8A03 will read the current time and date, and store it into the nine bytes 
starting at $8A06. The clock values assigned to the memory locations $8A06 
through $8A0E are shown below. 

$8A06: year 

$8A07: month 

$8A08: day of month 

$8A09:day ofweek 

$8A0A: hour 

$8A0B: minute 

$8A0C: second 

$8A0D: milliseconds (most significant 2 digits) 

$8A0E: milliseconds (least significant digit) 

Each of the values is stored in BCD form. Therefore, if the year is 1 985, $8A06 will 
contain $85. The millisecond count is in two bytes: the first two digits in $8A0D, 
and the third digit in $8A0E (as $xO). 



JSR $8A00 will allow you to issue any of the TPCE commands, in either 
immediate or deferred mode. In immediate mode, the output from the TIME, 
TIMER, RATE, and SLOT commands goes directly to the current output device 
(usually the screen, but not necessarily). In deferred mode, the output from those 
four commands is placed in the buffer starting at $0200. The output will be in 
ASCII, with high bit set, and terminated by a return character ($8D). 



In the routines shown below, the string address must be the address of your 
command buffer. It must contain an ASCII string terminated by a return character 
($8D or $0D). The contents of the ASCII string should be a valid TPCE command. 
TPCE copies the string to the buffer at $200, and then calls the regular TPCE 
parser to execute your command. 



CLC 




;signal immediate mode 


JSR 


$8A00 


;call TPCE 


.DA 


string. address 




BCS 


...error 




SEC 




;signal deferred mode 


JSR 


$8A00 


;call TPCE 


.DA 


string. address 




BCS 


...error 





If the carry flag is set when $8A00 returns, an error is indicated. The possible error 

codes, stored in the accumulator, are: 

$01 did not recognize the command name 

$02 command string was longer than 63 characters 

$1 syntax error or range error in command 
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